Configuring the web service for OpenID Connect

4.1 Configuring the web service for OpenID Connect

You can use either the standard authentication service (web.oauth2) or the standalone authentication service (web.oauth2.ext) to authenticate your users. The standalone authentication service does not require access to the MyID application server, but connects directly to the database; however, currently the standalone authentication service supports only FIDO as an authentication method.

For more information on the standalone authentication service, see section 2, Setting up the standalone authentication service.

Before you can use the MyID authentication service to verify the identity of an end user, you must configure the web service with the details of your external system and with the security protocols you want to use.

You can secure the request for an identity token in the following ways:

Using a shared secret.

When configuring your authentication service, you generate a secret code, then store a Base64-encoded SHA-256 hash of the code on the server; when you make the authentication code request, you provide your secret code securely over https, and the server compares it to the hash. The secret code is never stored on the server.

Important: You must keep the shared secret safe, as it can provide access to the features of the MyID authentication service. Do not use the same shared secret for end-user authentication and server-to-server API authentication.
Using PKCE.

For each authentication code request, you generate a secret code (known as the code verifier), then pass a Base64 URL-encoded SHA-256 hash of the code (known as the code challenge) in the request. When you exchange the authentication code for an identity token, you provide the code verifier, which the server compares to the code challenge to verify that the same system requested the original authentication code.

For more information on PKCE, including details of requirements for the code verifier and code challenge, see the Proof Key for Code Exchange by OAuth Public Clients RFC:

tools.ietf.org/html/rfc7636

You can use one or both of these methods. The examples in this document assume that you are using a combination of both methods.

For stateful web sites, where for example the server uses cookies to map stateful sessions between the client and the web server, it is recommended to configure the authentication service to require a client secret; you do not have to use PKCE, but you can use it in addition to the client secret if you want.

For single-page apps, which run entirely on the client PC, you must secure the request for authentication using PKCE; a shared secret is not appropriate.

Note: You must use TLS to ensure the security of the system. The MyID authentication service is configured to use TLS by default; you must not use OAuth2 OpenID Connect-based systems without TLS.

4.1.1 Creating a shared secret

If you are using a shared secret, you must generate an unguessable secret and create a hash to store on the server.

You are recommended to use a GUID for the secret.

If you are using the standalone authentication web service (web.oauth2.ext) you can use the provided GenClientSecret.ps1 PowerShell script to generate a GUID and create a SHA-256 hash converted to Base64:

On the web server, open a PowerShell window.
Navigate to the authentication service folder.

C:\Program Files\Intercede\MyID\web.oauth2.ext
Run the script:

.\GenClientSecret.ps1

The script generates a GUID to use as the shared secret, creates a SHA-256 hash from the GUID, then converts the hash to Base64; for example:

PS C:\Program Files\Intercede\MyID\web.oauth2> .\GenClientSecret.ps1

client secret: 82564d6e-c4a6-4f64-a6d4-cac43781c67c

SHA256+base64: kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=

Important: Do not use this example secret in your own system.
Take a note of the following values:
- client secret – you need this value for the client_secret parameter when posting to the token URL.
  
  See section 4.2.3, Requesting an identity token.
- SHA256+base64 – you need this value for the ClientSecrets parameter in the web service configuration file. The server does not store the secret, only the Base64-encoded hash.
  
  See section 4.1.2, Editing the configuration file.

The script uses the following code to generate the GUID and Base64-encoded hash:

Copy

Add-Type -AssemblyName System.Security
if ($args.count -ne 0)
{
  write-host "Usage: GenClientSecret"
  exit
}
$clientSecret = [guid]::NewGuid()

write-host "client secret: " $ClientSecret

$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
$hashBytes = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ClientSecret))

$Sha256Base64 = [Convert]::ToBase64String($hashBytes)
write-host "SHA256+base64: " $Sha256Base64

4.1.2 Editing the configuration file

In a text editor, open the appsettings.Production.json file for the web service.

By default, this is:

C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

If you are using a standalone web service, by default, this is:

C:\Program Files\Intercede\MyID\web.oauth2.ext\appsettings.Production.json

This file is the override configuration file for the appsettings.json file for the web service.
Edit the file to include the following:
Copy
```
{
    "Clients": [
        {
            "ClientId":  "<my client ID>",
            "ClientName":  "<my client name",
            "AccessTokenLifetime":  <access lifetime>,
            "IdentityTokenLifetime": <identity lifetime>,
            "AllowedGrantTypes": [
                "authorization_code"
            ],
            "RequireClientSecret": true,
            "RequirePkce": true,
            "AllowAccessTokensViaBrowser": true,
            "RequireConsent": true,
            "ClientSecrets": [
                {
                    "Value":"<secret>"
                }
            ],
            "AllowedScopes": [
                "openid"
            ],
            "AlwaysIncludeUserClaimsInIdToken":  true,
            "RedirectUris": [
                "<callback URL>"
            ],
            "AllowedCorsOrigins": [
                "<origin>"
            ],
            "Properties": {
                "EnableSelfService":  true,
                "Skin": "popover"
            }
        }
    ]
}
```
where:
- <my client ID> – the client ID you decided on; for example:
  
  myid.openid
  
  This represents your back-end system that intends to make calls to the MyID authentication service.
- <my client name> – an easily readable name for your client system; for example:
  
  My OpenID Connect System
- <access lifetime> – the time (in seconds) that the access token is valid. The default is 3600 – 1 hour.
- <identity lifetime> – the time (in seconds) that the identity token is valid. The default is 300 – 5 minutes.
- <secret> – if you are using a shared secret, set this to the Base64-encoded SHA-256 hash of the secret you created; for example:
  
  kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=
  
  See section 4.1.1, Creating a shared secret.
- <callback URL> – the URL of the web page on your system to which the authorization code will be returned.
- <origin> – used for Cross-Origin Resource Sharing (CORS). If the web page that calls the authentication service is on a different origin from the authentication service, you must add the origin to this list.
  
  Note: Make sure you use an origin, and not an URL, when configuring CORS. For example: https://myserver/ is an URL, while https://myserver is an origin.
You can set the following options:
- RequireClientSecret – set this to true if you are using a shared secret to secure the request.
- RequirePkce – set this to true if you are using PKCE to secure the request.
  
  Note: You must use a shared secret, PKCE, or both a shared secret and PKCE.
- RequireConsent – set this to true to allow the end-user to approve the external system's access to their identity information stored on your authentication service.
- AllowedScopes – set this to one of the values in the IdentityResources section of the appsettings.json file for the authentication service:
  - openid – returns the sub claim in the identity token; this is the subject ID of the end user, as stored in the UserAccounts.ObjectID field in the MyID database.
  - email – returns the email claim in the identity token; this is the email address of the user, as stored in the People.Email field in the MyID database.
    
    Note: The email claim is currently available only for FIDO authentication.
  - profile – returns the name claim in the identity token; this is the MyID logon name of the user, as stored in the UserAccounts.LogonName field in the MyID database.
- AlwaysIncludeUserClaimsInIdToken – set this to true to allow claims other than sub to be returned in the identity token. If you do not set this to true, setting AllowedScopes to include email and profile does not result in additional claims in the identity token.
- Properties – you can set the following:
  - Skin – currently only popover is available as a skin option for the authentication GUI. The authentication web page shows a background image with a popover representing the authentication UI; this is suitable for large windows. If you are displaying the authentication page in a small popup window, you can omit this option.
  - EnableFido2LoginBasicAssurance – set this to true to allow authentication using FIDO basic assurance authenticators, which provide only single-factor authentication.
  - EnableFido2LoginHighAssurance – set this to true to allow authentication using FIDO high assurance authenticators, which provide multi-factor authentication.
    
    When using FIDO with web.oauth2, authentication using high and basic assurance is controlled using the logon mechanisms feature; as the web.oauth2.ext standalone authentication service does not use the MyID application server, this feature is not available, and you must specify the logon mechanisms using the above options.
    
    For more information about basic and high assurance FIDO authenticators, see the Supported authenticators section in the FIDO Authenticator Integration Guide.
  - EnableAuthCodeLogin – set this to true to allow authentication using single-use authentication codes (assuming MyID is configured to use the Authentication Code logon mechanism), or false to prevent this client from using single-use authentication codes, even if MyID is configured for authentication codes for the MyID Operator Client.
    
    For more information on authentication codes, see the Configuring authentication codes for the MyID authentication server section in the Administration Guide.
  - EnablePassphraseLogin – set this to true to allow authentication using security phrases (assuming MyID is configured to use the Password Logon logon mechanism) or false to prevent this client from using security phrases, even if MyID is configured for security phrase logon for the MyID Operator Client.
    
    The default is true, which allows security phrase logon if MyID is configured to use Password Logon in the Logon Mechanisms tab of the Security Settings workflow.
  - EnableCardLogin – set this to true to allow authentication using a smart card (assuming MyID is configured to use the Smart Card Logon logon mechanism) or false to prevent this client from using smart cards to authenticate, even if MyID is configured for smart card logon for the MyID Operator Client.
    
    The default is true, which allows smart card logon if MyID is configured to use Smart Card Logon in the Logon Mechanisms tab of the Security Settings workflow.
  - EnableWindowsLogin – set this to true to allow authentication using a Integrated Windows Logon (assuming MyID is configured to use the Integrated Windows Logon logon mechanism) or false to prevent this client from using Windows credentials to authenticate, even if MyID is configured for Integrated Windows Logon for the MyID Operator Client.
    
    The default is true, which allows Integrated Windows Logon if MyID is configured to use Integrated Windows Logon in the Logon Mechanisms tab of the Security Settings workflow.
    
    See the Signing in using Windows authentication section in the MyID Operator Client guide for more information about configuring MyID for Integrated Windows Logon.
  - EnableHeadlessCardLogin – set this to true to allow authentication using a key pair; for example, for certificate renewal for mobile identities. MyID must also be configured to use the Smart Card Logon logon mechanism.
    
    The default is false. This setting is currently used only for the myid.rest.mobile client.
  - EnableHeadlessPassphraseLogin – set this to true to allow authentication using a key pair; for example, for certificate renewal for mobile identities. MyID must also be configured to use the Password Logon logon mechanism.
    
    The default is false. This setting is currently used only for the myid.rest.mobile client.
  - EnableSelfService – set this to true to allow people to launch the MyID Self-Service App from the MyID Authentication screen using the Manage My Credentials link; this allows people to manage their credentials without first signing in to MyID; for example, to change their security phrases or reset their device PIN. Set this property to false to prevent the Manage My Credentials link from being displayed.
    
    Note: The Allow Self-Service at Logon configuration option (on the Logon tab of the Security Settings workflow) must also be set for this option to appear.
Important: If you have clients in the appsettings.json file and the appsettings.Production.json file, make sure the production file does not overwrite the entries in the base file. In these settings files, entries in arrays are determined by their index; therefore if you have four existing entries in the appsettings.json file, you must include four blank array entries {}, in the appsettings.Production.json file before you include your new client details. Alternatively, you can include the entire Clients array in the appsettings.Production.json file.

Note: By default, the appsettings.Production.json file contains the myid.adfs client section in the appropriate place; see section 3.4, Configuring the standalone authentication service for AD FS for details.

For example:
Copy
```
{
    "Clients": [
        {},
        {},
        {},
        {},
        {
            "ClientId": "myid.openid",
            "ClientName": "My OpenID Connect System",
            "AccessTokenLifetime": 3600,
            "IdentityTokenLifetime": 300,
            "AllowedGrantTypes": [
                "authorization_code"
            ],
            "RequireClientSecret": true,
            "RequirePkce": true,
            "AllowAccessTokensViaBrowser": true,
            "RequireConsent": true,
            "ClientSecrets": [
                {
                    "Value": "kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk="
                }
            ],
            "AllowedScopes": [
                "openid"
            ],
            "AlwaysIncludeUserClaimsInIdToken":  true,
            "RedirectUris": [
                "https://myserver/mysystem/callback.asp"
            ],
            "AllowedCorsOrigins": [
                "http://myserver"
            ],
            "Properties": {
                "EnableSelfService":  true,
                "Skin": "popover"
            }
        }
    ]
}
```
If you already have an appsettings.Production.json file, back up the existing file, then incorporate the new client section above into the file.
Save the configuration file.
Recycle the web service app pool:
1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.
3. If you are using the standalone web service, right-click the myid.web.oauth2.ext.pool application pool, then from the pop-up menu click Recycle.
This ensures that the web service has picked up the changes to the configuration file.
Check that the authentication service is still operational by logging on to the MyID Operator Client.

Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

HTTP Error 500.30 - ANCM In-Process Start Failure

See section 4.3, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

As an alternative to logging on to the MyID Operator Client (for example, if you are using the standalone authentication service), you can check the following URL:

https://<myserver>/web.oauth2/.well-known/openid-configuration

For the standalone authentication service, this is:

https://<myserver>/web.oauth2.ext/.well-known/openid-configuration

where <myserver> is the address of the MyID authentication service. This should return a block of JSON describing the endpoints and configuration of your authentication service.

4.1.3 Configuring authentication to skip the MyID Authentication screen

You can configure authentication for web.oauth2 or the MyID Operator Client to skip the MyID Authentication screen; if there is a single logon mechanism enabled (due to other logon mechanisms being disabled in MyID security settings or in the web.oauth2 appsettings for a given oauth2 client) the user is not presented with the MyID Authentication screen when they authenticate. The single available logon mechanism that is enabled is automatically used. However, if the EnableSelfService option is set to true the MyID Authentication screen also displays a Manage My Credentials link; this means that MyID cannot skip the MyID Authentication screen.